Introduction

This is an example of a simple help file prepared using RTFGEN.  It will give you all the basics for constructing a similar file even if you've never written a help file before.

The basis for this help file is the topic file, SIMPLE.TPC.  You should either make a listing of SIMPLE.TPC or open the file in Notepad so that you can compare the topic file with the resulting help file as we go along.

What You'll Need

Topic File Structure

Topic Text

Paragraphs and Text

Jumps and Popups

Command Syntax

Topic Header

\topic Command

\keyword Command

\title Command

\browse Command

Compiling the Help File

Summary


What You'll Need

In addition to RTFGEN, you'll need :

Your favorite ASCII text editor.  Make sure it's operating in a mode where it doesn't insert unseen tabs to optimize white space.  While tabs have a place in help files, we won't be using them in this simple file.

The Microsoft Help Compiler, preferably the Windows 3.1 version.  It's usually shipped with the major programming packages and may be named HC31.EXE, HC.EXE, or HCP.EXE.  If you don't have it, you can probably download it.  See the References section of RTFGEN.HLP.

And of course, the WinHelp.EXE program that comes with Windows.


Topic File Structure

As you look through the SIMPLE.TPC file, you'll note that it starts with a \docstart command and ends with a \docend command.  In between, the file consists of a series of:

Topic headers

Where several commands are used to enter information for the help compiler.  The topic header section is terminated with 5 or more equal signs.

Topic text

This is the text which appears in the help file.  A row of 5 or more hyphens marks the end of the topic page.


Paragraphs and Text

This is an ordinary paragraph.  If you look at how it's entered in SIMPLE.TPC, the only thing that looks different is the ` (grave accent) at the end to mark the end of paragraph.  If you shrink the help window width, you'll notice that WinHelp reformats the paragraph to fit.  In other words, the carriage return-line feed combinations entered in the ASCII topic file are interpreted only as a single spaces.  It's the grave accent at the end which determines where the paragraph will end.

Here's how you make an indented paragraph.  Just indent the first line.  When typing this paragraph, I deliberatly messed up the indentation of the remaining lines to show that it's only the first line that matters.

Blank lines in the topic file result in blank lines in the help file.

Make a bold paragraph by preceding it with the \b command.

An italicized paragraph by preceding it with the \i command.

Or both bold and italicized.

You can change the font size in a paragraph by preceding it with the font size command, \fsNN.  Here, NN is a number representing the font pitch in half points.

To use these commands on only portions of the text, use the curly braces to enclose the part affected.  So you can have bold, italicized, or bold and italicized words or phrases and even BIG BOLD words.

Both RTFGEN and the Window's help compiler interpret certain characters in special ways.  These include the backslash, curly braces, square brackets, and grave accent.  If you need these characters in your text, they should be preceded with a backslash character as:

\  `  {  }  [  ]


Jumps and Popups

The syntax to create a jump hotspot is:

[Green Text :TopicName]

where square brackets are used to outline the jump, 'Green Text' will appear as underlined green in the text (the actual hotspot), and ':TopicName' is the topic name where the jump will go.  It will not appear in the help file text.

Click here to jump

The syntax for a popup hotspot is the same except two brackets are used on each end rather than one.

Click here to popup


You just jumped to the 'Jump' topic.  Click the 'Back' button to return.


This is a popup.


Command Syntax

Commands are used to supply information to both RTFGEN and the help compiler.  You've already seen a number of commands, but here's the official syntax :

Commands start with a backslash character.

The backslash is followed by a LOWER CASE alpha string which identifies the command.

Some commands have a single numerical parameter attached (no separating space).

In many cases a single space after the command is required to separate the command from text.  A single following space is considered part of the command -- any additional spaces are considered part of the text.

Unknown commands (possibly typos) are ignored.


Topic Header

Each topic in the topic file has a header section.  If you look at SIMPLE.TPC, you'll note that most topic headers have \topic, \keyword, \title, and \browse commands.

The topic header is terminated with a row of 5 or more equal signs.


\topic Command

Syntax:

\topic <symbol>`

where <symbol> is an Alphanumeric symbol which may also contain the period and underscore.  Spaces are not permitted.  <symbol> is not case sensitive.

The \topic command defines the symbol used to access the topic through jumps, popups, or context sensitive help.  Hence most topics will require this command.


\keyword Command

Syntax:

\keyword <phrase>`

\keyword <phrase1>;<phrase2>;<phrase3>`

where <phrase> may consist of anything except the semicolon.  The semicolon is used when multiple phrases are required.  More than one \keyword command may be used in a topic header if you have too many phrases to fit on one line.

If you press the WinHelp's Search button, topic keywords and phrases appear in the upper listbox.  These help you track down the topic you're looking for.


\title Command

Syntax:

\title <phrase>`

where <phrase> can be just about anything.

If you press the WinHelp's Search button, the topic titles appear in the lower listbox when the Show Topics button is pushed.


\browse Command

Simplified syntax:

\browse <symbol>`

where <symbol> is an alphanumeric symbol (not case sensitive).

The \browse command tells the help compiler how you want the browse buttons (the ones marked << and >>) to work.  Each browse sequence is defined by the same <symbol> and with this simplified syntax, the help compiler will sequence through the topics in the order in which they are inserted in the topic file.

This topic file has a single sequence called General which includes most of the topics.


Compiling the Help File

As you work on your topic file, from time to time you'll want to compile it and see what it looks like when displayed.  To see what's involved, you can try recompiling SIMPLE.TPC.  Here's the steps:

Start RTFGEN -- the title bar should say 'noname.hps'.  If it doesn't (you've already been using it) use File | New to get a fresh start.

Select Project | Topic Files to bring up the topic files dialog.  Click on 'Add File' and add the SIMPLE.TPC file to the project.  Then click on OK to exit the Topic Files dialog.

Select Project | Options to bring up the options dialog.  Most of the defaults will be applicable.

Check that the help compiler's name corresponds to that of your help compiler.

Under 'Title' enter the title you want on the help file's caption bar.

The 'Contents' entry tells the help compiler what topic you want to come up first and where the Contents button will take you.  If you leave this blank, the first topic will be used (correct in this case) but you can enter 'Introduction' just to be sure.

Use File | Save As to name the project.  Name it XSIMPLE.HPS (not SIMPLE.HPS or you'll eventually end up overwriting this SIMPLE.HLP file).  ThE XSIMPLE.HPS file is the one you'll later load to resume work on the project.

Select Compile | RTF only  and SIMPLE.TPC will be compiled to form SIMPLE.RTF, a Rich Text Format file that the help compiler can use for input.  At the same time, a help project file for the help compiler, XSIMPLE.HPJ, will be generated.

Select Compile | Help Compiler to run the help compiler and generate the XSIMPLE.HLP file.

Select Compile | Display Help File to call up WinHelp to display the help file.

You could have done all three of the last steps at once by selecting Compile | Full Compile, Display  (or by using the F9 hot key).

Normally, at this point, you'd want to go back to your editor and make changes or additions. The best way to do this is to leave RTFGEN on screen (even if just a corner shows).  Then when you've made your changes, save your file to disk (but leave the editor up), click on RTFGEN and press F9 to get a quick look at what you've done.  Then you can click on the editor to make more additions, etc, etc, etc.


Summary

At this point you should be able to write a simple but adequate help file.  But there's lots more that you can do that hasn't been illustrated here.  Here's some other things that are easy :

Changing fonts

Colored text

Adding bitmaps

Other paragraph styles such as centered or boxed

Using text macros to save typing

And much more

See the RTFGEN help file for more information.